Celestin Apprentice 7/Apprentice-Release7.iso/Source Code/C ++/Applications/TimGA 1.2.1/PP Archive ƒ/AGA Slider ƒ/Read Me

Text File | 1997-07-16 | 13.1 KB | 310 lines | [TEXT/CWIE]

AGA Slider:    A demo of class CAGASlider v 1.4.4                    April 8, 1997
    68K (Code works on PPC.)
    CodeWarrior 11 (can work in 9 and 10)
    PowerPlant

================================================================================

AGA Slider is a project for demonstrating the CAGASlider class.
It also includes CAGAProgressBar, CGAGroupBox and CBevelAttachment.

CAGASlider is a PowerPlant LControl that looks like a slider from
the Apple Grayscale Appearance for System 7. It is not a CDEF.

Apple's docs on the AGA show you what things look like to the pixel,
but, alas, they don't explain behaviors. I had to guess, mostly by
imitating the sliders in the system control panels. I have also added
a reasonable black and white appearance.

Feel free to send me any comments, suggestions, and bug-reports to:
  [e-mail] (James Jennings)
Thanks to all those who have already written. The feedback was very helpful.

The AGA classes in this project are
    copyright © 1996-1997 by James Jennings. All rights reserved.
This version of these classes may be freely used for non-commercial, shareware,
and commercial projects.

================================================================================

Features of CAGASlider:

    Mouse down in the indicator shows a "pressed" indicator.
    As indicator is dragged, the pressed indicator doesn't move and a "ghost"
        indicator follows the mouse.
    The ghost indicator slides under the pressed indicator.
    Clicking on the "track" jumps the indicator to that position.
    When the mouse is released, the real indicator moves to the ghost's last position.
    When the mouse is dragged away from the track, the ghost disappears. (Aborting.)
    Horizontal and vertical sliders are centered in the pane. (Needs >=16 pixel width.)
    "Pointing" sliders (which have tick marks) are aligned to the side of the pane away
        from the pointer and the tick marks. (Needs >=25 pixel width.)
    Sliders are drawn correctly when Disabled().
    Uses StOffscreenGWorld for flicker-free tracking.
    Looks reasonable on black and white screens.
    Looks reasonable when split across two monitors of different pixel depths. (Although,
        since I only have one monitor myself, this hasn't been tested as much as I'd like.)
    Has a "continuous broadcast" option for "active" sliders.
    The direction of increasing values can be changed in Constructor.
    The background color can be set in Constructor.

Features of CAGASliderForTabPanel:

    Changes it's background color to match that of an enabled or disabled LGATabPanel.

Features of CBevelAttachment:

    CBevelAttachment which allows you to add Grayscale Appearance
        style bevels to any pane using Constructor 2.2 or later.

Limitations:
    Doesn't have value labels. If you add your own (with an LCaption, say)
    be sure to gray them out when the CAGASlider is disabled.

    When disabled and on a black and white screen, CGAGroupBox will draw the text
    using a gray pattern. This will render the text illegible unless you use a font
    like Chicago 12 (which the AGA standard recommends.)

    Although you can use CBevelAttachment to add a "bevel" to an LEditField,
    (as I've done in this demo), note that it doesn't change when the field is disabled.
    CBevelAttachment requires CodeWarrior 9 or later.

Version History:

    v1.4.4:
        Fixed a bug (introduced in 1.4.2) that failed to always redraw the
            indicator/thumb when a drag was aborted.
        Added CAGASliderForTabPanel. If LView had a way of finding the
            background color of a superview, I wouldn't need this.

    v1.4.3
        Added the background color to the Constructor definition. (CPPb and CTYP)
            (My attempt to "auto-detect" the color didn't work with floating windows.)

    v1.4.2
        SetValue() will Draw() and Enable()/Disable() will Refresh() the slider. It
            was pointed out to me that this is the way most PowerPlant LControls work.
        CGAGroupBox and CAGAProgressBar now also draw themselves as appropriate.
        CAGAProgressBar was reworked slightly. See CProgressDemoWindow.

    v1.4.1
        Added some "#pragma unused" and "#include" directives.
        The Constructor files now include the CTYP resources needed in CW11.
        CAGASlider now detects and uses the background color that was drawn by the
            enclosing pane. (This didn't work in all cases and was removed in 1.4.3.)

    v1.4
        CAGAProgressBar.
        Fixed the slider's disabled track fill color.

    v1.3.1:
        Optimized so that it tracks the mouse better on slower machines.

    v1.3:
        "Ghost" indicator now slides under the real indicator. (Like the Speech control
            panel does.) (Thanks to Sarwat Khan for pointing out the obvious.)

    v1.2:
        The disabled state now matches the specification on the
            September 1996 Developer CD.
        The black and white disabled state is now drawn with a gray pattern.
        This distribution also includes a Group Box class (CGAGroupBox) based on
        LGroupBox, and CBevelAttachment which allows you to add Grayscale Appearance
            style bevels to any pane using Constructor 2.2 or later.

    v1.1:
        The direction of increasing values can be changed in Constructor.

================================================================================

CAGASlider's CTYP/CPPb resource (for Constructor) should define these members:

    Direction:    (Int32, viewed as Text)
        Values: hori, vert, nort, sout, east, west, prop
        Chooses the indicator type.
        nort, sout, east, west refer to the compass direction of "pointy" indicators.
        'prop' chooses hori or vert depending on the pane proportions.
        Note: These values are not stored. They are converted into an enumerated
            type in the CAGASlider constructor.
    Number of Tick Marks: (Uint16)
        Values:
            0: Don't show tick marks.
            1: Show one tick mark for each allowed value of LControl::mValue.
            n > 1: Show n tick marks (n-1 intervals).
        Note: Number of Tick Marks is ignored for hori and vert types.
    Continuous Broadcast: (Boolean)
        Values:
            false: BroadcastMessage() is called only when the slider is released (on mouseUp).
            true:  BroadcastMessage() is called every time the value changes during a drag.
    mMinValue is at Bottom or Right: (Boolean)
        Values:
            false: mValue == mMinValue when the slider is at the top
                (for vertical sliders) or the left (for horizontal sliders).
                This is the way standard scrollbars behave.
            true: mValue == mMinValue when the slider is at the bottom
                (for vertical sliders) or the right (for horizontal sliders).
                This may be more intuitive for some vertical sliders. ("up is more")
    Background Color: (RGBColor)
        Values: any RGBColor. Default is AGA 2 = {0xDDDD, 0xDDDD, 0xDDDD}
            A slider inside a tab group will need AGA 1 = {0xEEEE, 0xEEEE, 0xEEEE}

There is also a file called CAGASlider1.4.4.CTYP which defines CAGASlider for Constructor.
It has been hacked so that the Direction appears as a pop-up menu.
The best way to use it is to place it in the same folder with Constructor
so that Constructor (v2.2 or later) will load it on startup.

*** Note: Constructor 2.2 cannot edit CAGASlider4.4.CTYP without crashing. ***
          Constructor 2.3 (CW10) will politely decline to edit it.
          Constructor 2.4 actually shows you the definition. Progress?

If you need a CPPb that you can edit, use the file "CAGASlider1.4.CTYP (no popup)"
found in the "(Backward compatibility)" folder.

================================================================================

CAGASliderForTabPanel is subclassed from CAGASlider and doesn't define any new members.

================================================================================

CAGAProgressBar's CPPb/CTYP resource (for Constructor) doesn't define any new members.

"Indeterminant" Progress Bars:
    Set the Minimum == the Maximum in Constructor.
        (Or call SetMinValue() and SetMaxValue() with the same argument.)
    Indeterminant bars are updated every time SetValue() is called,
        although the argument of SetValue() is ignored
    You can keep from drawing too often by calling SetValueDelayedDrawing()

There is a file called CAGAProgressBar.CTYP which defines CAGAProgressBar for Constructor.

================================================================================

CGAGroupBox's CPPb/CTYP resource (for Constructor) should define one member:

    Primary/Secondary: (Boolean)
        Values:
            true: Draw a "primary" group box.
            false: Draw a "secondary" group box. (For use inside a primary group box.)

There is a file called CGAGroupBox.CTYP which defines CGAGroupBox for Constructor.

================================================================================

CBevelAttachment's CPPb/CTYP resource (for Constructor) should define these members:

    Bevel In: (Boolean)
        If true, draw a bevel that makes the pane look recessed. Otherwise,
        draw a bevel that makes the pane look raised.
    Width: (Int16)
        How wide to draw the bevel. Usually 1 or 2.
        If you make this negative, the bevel will be drawn outside the the edge
            of the pane. Note that this might not always get updated properly.
    Fill with white: (Boolean)
        If true, erase the center of the view with white. If false, do nothing.

There is a file called CBevelAttachment.CTYP which defines CBevelAttachment for Constructor.
Note that Attachments are not supported by Constructor before version 2.2 (CW9).

================================================================================

To add CAGASliders to your project:

    To a PowerPlant "Starter" project you will need to add the files:
        CAGASlider.cp
        AGA Slider Parts PICTs.rsrc
        UGrayscaleAppearance.cp
        UGWorld.cp
    You will also need:    (in your project folder)
        CAGASlider.h
        UGrayscaleAppearance.h
    and:    (in Constructor's folder)
        CAGASlider1.4.CTYP
    You will also need to register the ClassCreatorFunc in your app's constructor.

To add CAGAProgressBar to your project:

    To a PowerPlant "Starter" project you will need to add the files:
        CAGAProgressBar.cp
        AGA Progress Bar Parts.rsrc
        UGrayscaleAppearance.cp
        UGWorld.cp
    You will also need:    (in your project folder)
        CAGAProgressBar.h
        UGrayscaleAppearance.h
    and:    (in Constructor's folder)
        CAGAProgressBar.CTYP
    You will also need to register the ClassCreatorFunc in your app's constructor.

To add CGAGroupBox to your project:

    To a PowerPlant "Starter"  project you will need to add the files:
        LGroupBox.cp
        CGAGroupBox.cp
        UGrayscaleAppearance.cp
    You will also need:
        LGroupBox.h
        CGAGroupBox.h
        UGrayscaleAppearance.h
        CGAGroupBox.CTYP (in Constructor's folder)
    You will also need to register the ClassCreatorFunc in your app's constructor.

To add CBevelAttachment to your project:

    To a PowerPlant "Starter"  project you will need to add the files:
        CBevelAttachment.cp
        UGrayscaleAppearance.cp
    You will also need:
        CodeWarrior release 9 or later.
        CBevelAttachment.h
        UGrayscaleAppearance.h
        CBevelAttachment.CTYP (in Constructor's folder)
    You will also need to register the ClassCreatorFunc in your app's constructor.

================================================================================

Programming Notes:

CAGASlider inherits from LControl and UGrayscaleAppearance.
CAGAProgressBar inherits from LControl and UGrayscaleAppearance.
CGAGroupBox inherits from LGroupBox and UGrayscaleAppearance.
CBevelAttachment inherits from LAttachment and UGrayscaleAppearance.

UGrayscaleAppearance encapsulates the AGA color definitions and a few utility functions.

I set the background color of the Demo's windows to gray by setting its "content" color
in ResEdit. This adds a 'wctb' resource. There is no code in the project that draws
the background color for the whole window, just for the sliders.

The slider allocates some memory for holding the indicator (thumb) images. These
images are shared by all sliders in the application, and normally hang around
until the application quits. If you want to be really fanatic about freeing up
memory (it's only a few K), you can call CAGASlider::Purge().

The progress bar allocates some memory for holding fill patterns and such. These
graphics are shared by all progress bars in the application, and normally hang around
until the application quits. If you want to be really fanatic about freeing up
memory (it's only a few K), you can call CAGAProgressBar::Purge().

I deliberately made the slider so that the indicator "snapped to" the allowed
values of the slider. If you want a smoother feel, try increasing the range
of the slider values until it looks smooth, and then adjust the result of GetValue()
before you use it. For an example, note that the demo has some sliders with 10
intervals, and some with 100 intervals.

When I switched from Apple's April 96 specification to the Sept 96 specification, I
made it conditionally compiled. To revert to the April specification:
    #define AGA_VERSION 1 in both CAGASlider and CGAGroupBox
    Replace the file "AGA Slider Parts PICTs.rsrc" with "AGA Slider Parts PICTs Apr.rsrc"

Progress Bars are drawn 14 pixels high. In Constructor, set the pane height to
at least 14. More doesn't hurt. Less will trigger some debugging code.

CBevelAttachment requires Codewarrior release 9 or better.
To compile the demo under CW8 or earlier:
    1) replace the file "AGA Slider.rsrc" with "AGA Slider.rsrc (no bevel)"
    2) remove the file CBevelAttachment.cp from the project.
    3) remove the references to CBevelAttachment that appear in AGASliderApp.cp

James Jennings
[e-mail]